[COPYRIGHT © 2025 RIBBON COMMUNICATIONS OPERATING COMPANY, INC. ALL RIGHTS RESERVED]: # # Voice and Video Calls using Async APIs In this quickstart, we will cover the basics of making calls with the WebRTC JS SDK's Async APIs. Code snippets will be used to demonstrate call usage of the SDK, and together these snippets will form a working demo application that can be viewed at the end. For information about other call features, such as mid-call operations or screensharing, please refer to their respective quickstarts. #### Async vs. non-Async APIs The newly introduced Async APIs provide an alternate version of the SDK's APIs that provide feedback via promises instead of emitting events. Every API has an Async API equivalent, which performs the same underlying behaviours, but provides feedback in a friendlier way for applications to handle. If you are interested in a more thorough comparison between the Async and non-Async versions of the SDK's APIs, we recommend also reading our [Async APIs Tutorial](Async%20APIs.md). This quickstart is the Async API equivalent to our [Voice and Video Calls Quickstart](Voice%20and%20Video%20Calls.md). Some of this quickstart's explanations will reference the non-Async APIs, but familiarity of them is not required. Additionally, some portions of the quickstart that are unchanged between the Async and non-Async APIs (notably, the user interface and SDK configurations) are omitted here. ## User Subscription with Async APIs The same flow of APIs is required whether using the regular or Async APIs: Set User Credentials, Subscribe, then eventually Unsubscribe. #### Set Credentials The `setCredentialsAsync` API behaves exactly as the `setCredentials` API except for one thing: On failure, the API will throw an error. This means that the application receives the feedback from the API immediately when called, instead of needing to listen for the `auth:change` event that would be emitted for the `setCredentials` API. So in this tutorial, we do not need any event listeners for setting user credentials. ```javascript /* * Set User Credentials. */ function setCredentialsAsync () { const username = document.getElementById('username').value const password = document.getElementById('password').value try { client.setCredentialsAsync({ username, password }) const user = client.getUserInfo() document.getElementById('current-user').innerHTML = user.username document.getElementById('subscribeBtn').disabled = false log('Credentials set as user: ' + user.username) } catch (error) { log('Failed to set credentials: ' + error.message + ' (' + error.code + ')') } } ``` Note: Though this API's name is suffixed with "Async", it is not asynchronous and does not return a promise. The "Async" suffix is used to indicate the new APIs that provide feedback via return values instead of events, which are promise-based but have a few exceptions such as this API. #### Subscribe & Unsubscribe Similarly to the `setCredentialsAsync` API, the `subscribeAsync` and `unsubscribeAsync` APIs do not need event listeners. The `subscribe` and `unsubscribe` APIs would require the application to listen for the `subscription:change` event, but we do not need that here for _solicited_ subscription changes. For `subscribeAsync` and `unsubscribeAsync`, handling the returned promise tells us everything we need to know: on resolve, the user is now subscribed, or on reject, the subscription failed. ```javascript /* * Subscribe. */ async function subscribeAsync () { try { await client.services.subscribeAsync(['call']) setSubscribedUI(true) const services = client.services.getSubscriptions() log('Subscribed services: ' + services.subscribed) } catch (error) { log('Subscription error: ' + error.message + ' (' + error.code + ')') } } /* * Unsubscribe. */ async function unsubscribeAsync () { try { await client.services.unsubscribeAsync(['call']) setSubscribedUI(false) const services = client.services.getSubscriptions() log('User unsubscribed.') } catch (error) { log('Unsubscription error: ' + error.message + ' (' + error.code + ')') } } ``` ## Step 1: Making a Call When making an outgoing call, the application needs to provide at least a `destination` and a `media` parameter. The `media` parameter indicates what local media should be included on the call, which will be audio and optionally video for this tutorial. The `makeAsync` API's promise will resolve with the newly made call when it enters `Initiated` state. At this point, the call is waiting to be answered by the destination. ```javascript // Variable to keep track of the current call. let call /* * Make an outgoing call. */ async function makeCallAsync () { const destination = document.getElementById('callee').value try { log('Making call to ' + destination) const withVideo = document.getElementById('make-with-video').checked // Track the current call with the global `call` variable. call = await client.call.makeAsync(destination, { audio: true, video: withVideo, videoOptions: withVideo ? { width: 400, height: 400 } : undefined }) log('Call successfully started. Waiting for response.') } catch (error) { log('Failed to call: ' + error.message + + '(' + error.code + ')') } } ``` As the call is being made, the SDK will emit `call:tracksAdded` events to indicate media is now available on the call and can be rendered. This application will render the tracks in the event listener for `call:tracksAdded`, since that event will be emitted for any scenario where new tracks are available, rather than only when making a call. When the call is answered, a `call:stateChange` event will be emitted to indicate the call's state has changed to `Connected`. There is nothing this application needs to do in this scenario. ## Step 2: Responding to a Call Just like in the [Voice and Video Calls Quickstart](Voice%20and%20Video%20Calls.md), an incoming call can be answered or rejected. Similarly to making a call, answering a call requires a `media` parameter that indicates what local media should be included on the call. This quickstart will always include audio and conditionally include video. ```javascript /* * Answer an incoming call. */ async function answerCallAsync () { try { // If the incoming call offered video and the local user indicates to also send video, then answer with video. const videoOffered = call.mediaOffered?.video const withVideo = videoOffered && document.getElementById('answer-with-video').checked await client.call.answerAsync(call.id, { audio: true, video: withVideo, videoOptions: withVideo ? { width: 400, height: 400 } : undefined }) log('Call answered.') } catch (error) { log('Failed to answer call: ' + error.message) } } ``` Similarly when making a call, the SDK will emit a `call:tracksAdded` event while it is being answered. The same event listener logic mentioned for the `makeAsync` API will handle rendering tracks for both the make and answer (and other) scenarios. When the call is answered, a `call:stateChange` event will be emitted to indicate the call's state has changed to `Connected`. There is nothing this application needs to do in this scenario. Rejecting a call is even simpler since it requires no extra parameters. Simply call the `rejectAsync` API: ```javascript /* * Reject the call. */ async function rejectCallAsync () { try { await client.call.rejectAsync(call.id) log('Rejected call.') } catch (error) { log('Failed to reject call: ' + error.message) } } ``` When the call is rejected, the SDK will also emit a `call:stateChange` event to indicate the call state has changed to `Ended`. We will use this event for call & UI clean-up, since it is emitted in all scenarios where the call is ended, not only when we call the `rejectAsync` API. ## Step 3: Ending a Call To end a call, we simply need to call the `endAsync` API. The API's returned promise tells us when the call has been ended. ```javascript // End call, asynchronously. async function endCallAsync () { try { await client.call.endAsync(call.id) log('Ended call.') } catch (error) { log('Failed to end call: ', error.message) } } ``` Similarly when rejecting a call, the SDK will emit a `call:stateChange` event to indicate its state has changed to `Ended`. So the same event listener logic mentioned for the `rejectAsync` API will handle both reject and end scenarios. ## Step 4: Call Events Though the Async APIs provide their feedback via promises instead of events, there are still events that are emitted to indicate state changes in the SDK or a specific call. The majority of these events are handled the same whether an Async or non-Async API was called, since they are not directly to an API. But there are a few events that are conceptually simpler when Async APIs are used, since they do not need to provide feedback for the APIs themselves anymore. The call events where handling is unchanged between API types are: 1. `call:receive`: Indicates that a new incoming call has been received. 2. `call:tracksAdded`: Indicates the call has new media that can be rendered. 3. `call:tracksRemoved`: Indicates the call has media that is no longer available, and should be unrendered. In contrast, the call event who's handling is simplified with Async APIs is the `call:stateChange` event. With Async APIs, it only indicates that the call's state has changed. So this quickstart will use the event to learn when the call ends ``` javascript // Listen for when the call changes state. client.on('call:stateChange', function (params) { call = client.call.getById(params.callId) log('Call state changed from ' + params.previous.state + ' to ' + call.state) // Clean-up the app state if the call is now ended. if (call.state === 'Ended') { call = null document.getElementById('answer-with-video').disabled = false } }) ``` When using the non-Async APIs, this event can also contain error feedback. The event no longer contains that for Async APIs since the feedback is provided via promises instead. ## Live Demo Want to play around with this example for yourself? Feel free to edit this code on Codepen.
[COPYRIGHT © 2025 RIBBON COMMUNICATIONS OPERATING COMPANY, INC. ALL RIGHTS RESERVED]: #